Fix pre-release review findings: dist AmiSSL guard, TLS handshake hangs, doc drift - #19

…gs, doc drift

Four independent reviewers (correctness, release mechanics, docs, Amiga
pitfalls) went over the repo before the next tag. Two release blockers
and several should-fixes, all fixed here and re-verified:

Release blockers:

- Makefile: `make dist` neither fetched the AmiSSL SDK nor required it,
  so a fresh checkout (exactly what release.yml's dist job does) would
  silently link a TLS-less mqtt.library while midge.readme advertises
  TLS as shipped. `dist` now fetches the SDK itself if missing and
  re-invokes `build` as a sub-make (M68K_HAS_AMISSL is a `:=`
  immediate-expansion variable, fixed at outer-make parse time - only a
  fresh sub-make process re-evaluates it against the now-populated
  .cache/), then hard-fails if the resulting mqtt.library still has no
  AmiSSL support - a permanent mechanical guard against this whole class
  of regression, not just a one-time fix. Verified: ran `make dist` for
  real inside the CI container from a clean .cache/, confirmed the
  AmiSSL-presence grep both passes on a real TLS build and correctly
  fails a deliberately non-TLS one.

- src/amiga/transport_amissl.c: the TLS handshake loop had no deadline
  and, inside mqtt.library's connection subprocess, no way to abort -
  break_sigmask is only wired up *after* connect() returns, and
  wait_gate() deliberately treats a break_sigmask wake as a retry, not
  an abort. A peer that accepts the TCP connect but stalls the handshake
  (tarpit, wrong service on the port, wedged broker) hung the caller
  forever with no recovery short of a reboot - MQTT_Disconnect()/
  MQTT_DeleteClient() couldn't reach the wedged child either. Added a
  30s elapsed-time budget (tool_now_ms()) to the loop. Re-verified both
  on-target smoke tests (library-tls-smoke, library-cafile-smoke) still
  pass end-to-end against real AmiSSL under Copperline.

Also fixed (real defect, not blocking):

- src/host/transport_openssl.c: a single SSL_connect() call on a
  blocking socket with a 1s SO_RCVTIMEO can return SSL_ERROR_WANT_READ
  when a read hits that timeout - blocking mode doesn't change what
  OpenSSL reports, only whether recv() itself blocks. One lost packet
  mid-handshake or a slow broker made `mqtt_pub -s` fail spuriously.
  Added the same bounded WANT_READ/WANT_WRITE retry loop (30s budget)
  transport_amissl.c already had to have. Re-verified: broker-tls-smoke
  passes (verify-on, skip-verify, and untrusted-cert-rejected cases).

- scripts/verify-version.sh (issue #9): now also checks
  MIDGE_VERSION_DATE actually changed since the previous release tag
  (format-validated too), closing the gap where a release PR bumping
  MIDGE_VERSION but forgetting the date would pass every existing check
  and ship binaries whose $VER carries the previous release's date.
  Verified against three cases: real bump (passes), version bumped with
  date left stale (fails with the new check), version unchanged
  (unaffected).

Docs drift:

- userdocs/CLI-Reference.md: the ReadArgs template code blocks were
  missing TLS/TLSINSECURE/CAFILE even though the argument tables right
  below them documented all three; "two flags that only exist on the
  host builds so far" was stale twice over (three flags, and no longer
  host-only since the Amiga transport shipped).
- README.md: the Status/Features sections still said TLS "is next" and
  pointed at docs/ARCHITECTURE.md's roadmap section, which was
  deliberately trimmed to shipped history and no longer covers
  post-v0.1 work (that's tracked via GitHub issues now, as the file
  itself says).
- userdocs/mqtt-library.md: never mentioned mco_TLS/mco_TLSInsecure/
  mco_CAFile at all; the error-code table was missing MQTTERR_STATE
  (-205) and mischaracterized MQTTERR_NOSTACK as something that can
  actually be returned (it's reserved - MQTT_CreateClient() returns a
  bare NULL on every creation failure). Added a TLS section, including
  the one real semantic difference from the CLI worth calling out:
  mco_TLSInsecure does NOT imply mco_TLS the way TLSINSECURE/-S implies
  TLS/-s on the CLI - it's simply ignored without mco_TLS set.

Deliberately not changed, for the user to decide:
- The actual version bump (0.1 -> next) - that's its own release PR per
  CLAUDE.md's process, not something to fold into a fixes PR.
- Enabling `run-dist: true` in ci.yml's per-push CI (would have caught
  the dist blocker earlier, but changes CI cost/cadence - a judgment
  call, not a fix).
- wait_gate()'s theoretical WaitSelect-failure misclassification and
  transport_openssl.c's low-confidence stale-errno edge case in
  openssl_recv() - both flagged as pre-existing patterns/unconfirmed
  triggers by the reviewers themselves, not concrete bugs.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QWq1CRLCQy9AaD9UtLRSM9